Description

In this example, the TRIDENT authentication and authorization API is used to authenticate the users of a document signature portal (https://docsign.safelayer.com) using Facebook. This authentication allows users to log in to the website. It is triggered when the user clicks on the Login button associated to the Facebook authentication mechanism.

The website is registered as an OAuth 2.0 client application in a TRIDENT system (txeidas.safelayer.com) and https://docsign.safelayer.com/oauth/callback is the only redirect URL established. When registered, the website obtained an identifier (docsign) and a secret shared with TRIDENT (demodemo), and was associated to an authorization server called main, which has the following endpoints:

Endpoint	Value
Authorization Endpoint	`https://txeidas.safelayer.com/trustedx-authserver/oauth/main`
Access Token Endpoint	`https://txeidas.safelayer.com/trustedx-authserver/oauth/main/token`
UserInfo Endpoint	`https://txeidas.safelayer.com/trustedx-resources/openid/v1/users/me`

The authorization server delegates user authentication to an IdP of the platform called eidas-provider and intermediates between the portal and the users so that these users can authorize the portal for accessing their identity data and the details of their authentication process at the endpoint https://txeidas.safelayer.com/trustedx-resources/openid/v1/users/me. Furthermore, TRIDENT is configured so that the only authentication requirements for the users are those specified in the authorization requests (acr_values parameter).

Obtaining Authorization

Request

When the user clicks on the Login button in the browser's window, the website responds with the following HTTP redirect response (see the Obtain Authorization operation):

HTTP/1.1 302 Found
Location: https://txeidas.safelayer.com/trustedx-authserver/oauth/main?response_type=code
                                  &client_id=doc_sign
                                  &redirect_uri=https://docsign.safelayer.com/oauth/callback
                                  &scope=urn:safelayer:eidas:full_identity urn:safelayer:eidas:authn_details
                                  &acr_values=urn:safelayer:tws:policies:authentication:flow:basic:facebook
                                  &state=99de239bebd2fe9d93afcd9cff2a47b26a85c0a6015b317b08385e02cebd95bc

Note that the website requests authorization for accessing the identity data of the user and the data on the authentication process carried out on them (scope=urn:safelayer:eidas:full_identity urn:safelayer:eidas:authn_details). Note also that the website requests that the user is authenticated with a flow that delegates authentication to Facebook (acr_values=urn:safelayer:tws:policies:authentication:flow:basic:facebook).

When the browser receives this redirect response, it sends the following HTTP request to TRIDENT:

GET /trustedx-authserver/oauth/main?response_type=code
                                  &client_id=doc_sign
                                  &redirect_uri=https://docsign.safelayer.com/oauth/callback
                                  &scope=urn:safelayer:eidas:full_identity urn:safelayer:eidas:authn_details
                                  &acr_values=urn:safelayer:tws:policies:authentication:flow:basic:facebook
                                  &state=99de239bebd2fe9d93afcd9cff2a47b26a85c0a6015b317b08385e02cebd95bc HTTP/1.1
Host: txeidas.safelayer.com:443

Response

After authenticating the user and obtaining their authorization for the website to access their identity and authentication data, TRIDENT redirects the browser to the website's redirect URL, after including in it the authorization code granted (the code parameter of the query string). As a result of the redirect, the browser performs the following HTTP request to the signature site:

GET /oauth/callback?code=87ad722b7705192382685091ae68aec0322cb1ca397c63ead348c3052865070d
                   &state=99de239bebd2fe9d93afcd9cff2a47b26a85c0a6015b317b08385e02cebd95bc HTTP/1.1
Host: docsign.safelayer.com:443

As well as extracting the code for the authorization granted (code), the website must extract the state parameter and check that its value matches the value of the state parameter in the request.

Obtaining the Access Token

Request

After obtaining the authorization code, the signature website requests the access token it needs to access the user's data. To do this, it sends the following request to TRIDENT (see the Obtain a Token operation):

POST /trustedx-authserver/oauth/main/token HTTP/1.1
Host: txeidas.safelayer.com:443
Authorization: Basic ZG9jc2lnbjpkZW1vZGVtbw==
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
 
grant_type=authorization_code&code=87ad722b7705192382685091ae68aec0322cb1ca397c63ead348c3052865070d

Note that the website must use its identifier and the secret it shares with TRIDENT to authenticate using the HTTP basic authentication scheme (RFC 2617). Also note that to obtain the access token, the website must include the authorization code in the request (code).

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Cache-Control: no-store, no-cache, must-revalidate
Pragma: no-cache
 
{
   "access_token" : "c9597ed2551a764d72d687fb2ec511822ae224180376c7632e2515d038639920"
   "token_type" : "bearer",
   "expires_in" : 120
}

Obtaining the User Data

Request

The website requests the identity data of the user and the information on their authentication process by sending the following request to TRIDENT (see the Obtain Information About the Authenticated User operation):

GET /trustedx-resources/openid/v1/users/me HTTP/1.1
Host: txeidas.safelayer.com:443
Authorization: Bearer c9597ed2551a764d72d687fb2ec511822ae224180376c7632e2515d038639920

Note that the website demonstrates its authorization for accessing the data requested by including the access token (c959...9920) in the Authorization header. Note also that the portal does not specify what specific information it wants to obtain as this information is determined by the scope of the access token included in the request.

Response

The website receives an HTTP response with a JSON object containing the identity attributes of the user and information on their authentication process.

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
  
{
   "sub" : "john.doe",
   "domain" : "eidas-provider",
   "username" : "john.doe",
   "email" : "john.doe@example.com",
   "email_verified" : true,
   "phone_number" : "00123456789",
   "distinguished_name" : "CN=john.doe, O=Example",
   "name" : "John Doe",
   "updated_at" : 1405897200,
   "groups" : [ "Marketing", "Sales" ],
   "acr" : "urn:safelayer:tws:policies:authentication:flow:basic:facebook"
   "authn_details" : {
        "authnFlow" : "urn:safelayer:tws:policies:authentication:flow:basic:facebook",
        "authnLevel" : "urn:safelayer:tws:policies:authentication:level:medium",
        "directSso" : "false",
        "targetAcr" : "urn:safelayer:tws:policies:authentication:flow:basic:facebook"
   }
}

For reasons of security, we recommend checking that the user was authenticated with the authentication flow requested. To do this, a check must be run that the flow specified in the acr property matches the flow in the acr_values parameter of the authorization request

Using the information in the response, the signature website creates a session for the user. Among the data stored in the session, the website includes the level of assurance of the user's identity (authn_details.authnLevel property). Thus, the portal can request the reauthentication of the user if the user makes a request that can only be attended if their identity is known with a higher level of assurance (step-up)

.